home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / gcc / gcc263_doc.lha / gnu / man / man1 / libm.1 < prev    next >
Text File  |  1994-12-19  |  15KB  |  463 lines
  1. /*
  2.  * Copyright (c) 1985 Regents of the University of California.
  3.  * All rights reserved.
  4.  *
  5.  *  Redistribution  and  use  in source and binary forms, with or
  6. without
  7.  * modification, are permitted provided that the following condi-
  8. tions
  9.  * are met:
  10.  *  1. Redistributions of source code must retain the above copy-
  11. right
  12.  *    notice, this list of  conditions  and  the  following  dis-
  13. claimer.
  14.  *  2.  Redistributions  in  binary form must reproduce the above
  15. copyright
  16.  *    notice, this list of  conditions  and  the  following  dis-
  17. claimer in the
  18.  *    documentation and/or other materials provided with the dis-
  19. tribution.
  20.  * 3. All advertising materials mentioning  features  or  use  of
  21. this software
  22.  *    must display the following acknowledgement:
  23.  *   This  product  includes software developed by the University
  24. of
  25.  *   California, Berkeley and its contributors.
  26.  * 4. Neither the name of the University nor  the  names  of  its
  27. contributors
  28.  *     may  be  used  to endorse or promote products derived from
  29. this software
  30.  *    without specific prior written permission.
  31.  *
  32.  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS
  33. IS'' AND
  34.  *  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  35. TO, THE
  36.  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR  A  PAR-
  37. TICULAR PURPOSE
  38.  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS
  39. BE LIABLE
  40.  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY,  OR
  41. CONSEQUENTIAL
  42.  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTI-
  43. TUTE GOODS
  44.  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTER-
  45. RUPTION)
  46.  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CON-
  47. TRACT, STRICT
  48.  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  49. IN ANY WAY
  50.  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSI-
  51. BILITY OF
  52.  * SUCH DAMAGE.
  53.  *
  54.  * K.C. Ng, with Z-S. Alex Liu, S. McDonald, P. Tang, W. Kahan.
  55.  *  Revised  on  5/10/85,  5/13/85,  6/14/85,  8/20/85,  8/27/85,
  56. 9/11/85.
  57.  *
  58.  *   @(#)README     5.4 (Berkeley) 10/9/90
  59.  */
  60.  
  61. ******************************************************************************
  62. *  This is a description of  the  upgraded  elementary  functions
  63. (listed  in  1).  * *  Bessel functions (j0, j1, jn, y0, y1, yn),
  64. floor, and fabs passed over    * *  from  4.2BSD  without  change
  65. except  perhaps for the way floating point      * *  exception is
  66. signaled on a VAX.  Three lines that contain "errno" in erf.c*  *
  67. (error functions erf, erfc) have been deleted to prevent overrid-
  68. ing        the          *        *         system        "errno".
  69. *
  70. ******************************************************************************
  71.  
  72. 0. Total number of files: 40
  73.  
  74.         IEEE/Makefile     VAX/Makefile     VAX/support.s    erf.c
  75. lgamma.c
  76.         IEEE/atan2.c     VAX/argred.s     VAX/tan.s         exp.c
  77. log.c
  78.         IEEE/cabs.c      VAX/atan2.s     acosh.c         exp__E.c
  79. log10.c
  80.         IEEE/cbrt.c     VAX/cabs.s       asincos.c        expm1.c
  81. log1p.c
  82.         IEEE/support.c   VAX/cbrt.s       asinh.c         floor.c
  83. log__L.c
  84.         IEEE/trig.c      VAX/infnan.s      atan.c            j0.c
  85. pow.c
  86.         Makefile          VAX/sincos.s      atanh.c          j1.c
  87. sinh.c
  88.         README           VAX/sqrt.s        cosh.c            jn.c
  89. tanh.c
  90.  
  91. 1. Functions implemented :
  92.     (A). Standard elementary functions (total 22) :
  93.         acos(x)                 ...in file  asincos.c
  94.         asin(x)                 ...in file  asincos.c
  95.         atan(x)                 ...in file  atan.c
  96.         atan2(x,y)                 ...in    files   IEEE/atan2.c,
  97. VAX/atan2.s
  98.         sin(x)                     ...in    files    IEEE/trig.c,
  99. VAX/sincos.s
  100.         cos(x)                     ...in    files    IEEE/trig.c,
  101. VAX/sincos.s
  102.         tan(x)                     ...in    files    IEEE/trig.c,
  103. VAX/tan.s
  104.         cabs(x,y)                  ...in    files    IEEE/cabs.c,
  105. VAX/cabs.s
  106.         hypot(x,y)                 ...in    files    IEEE/cabs.c,
  107. VAX/cabs.s
  108.         cbrt(x)                    ...in    files    IEEE/cbrt.c,
  109. VAX/cbrt.s
  110.         exp(x)                  ...in file  exp.c
  111.         expm1(x):=exp(x)-1      ...in file  expm1.c
  112.         log(x)                  ...in file  log.c
  113.         log10(x)                ...in file  log10.c
  114.         log1p(x):=log(1+x)      ...in file  log1p.c
  115.         pow(x,y)                ...in file  pow.c
  116.         sinh(x)                 ...in file  sinh.c
  117.         cosh(x)                 ...in file  cosh.c
  118.         tanh(x)                 ...in file  tanh.c
  119.         asinh(x)                ...in file  asinh.c
  120.         acosh(x)                ...in file  acosh.c
  121.         atanh(x)                ...in file  atanh.c
  122.  
  123.     (B). Kernel functions :
  124.         exp__E(x,c)    ...in    file    exp__E.c,     used     by
  125. expm1/exp/pow/cosh
  126.         log__L(s)   ...in file log__L.c, used by log1p/log/pow
  127.         libm$argred  ...in file VAX/argred.s, used by VAX version
  128. of sin/cos/tan
  129.  
  130.     (C). System supported functions :
  131.         sqrt()      ...in files IEEE/support.c, VAX/sqrt.s
  132.         drem()      ...in files IEEE/support.c, VAX/support.s
  133.         finite()    ...in files IEEE/support.c, VAX/support.s
  134.         logb()      ...in files IEEE/support.c, VAX/support.s
  135.         scalb()     ...in files IEEE/support.c, VAX/support.s
  136.         copysign()  ...in files IEEE/support.c, VAX/support.s
  137.         rint()      ...in file  floor.c
  138.  
  139.  
  140.    Notes:
  141.        i. The codes in files ending with ".s" are written in  VAX
  142. assembly
  143.           language. They are intended for VAX computers.
  144.  
  145.           Files  that  end  with  ".c" are written in C. They are
  146. intended
  147.           for either a VAX or a machine that conforms to the IEEE
  148.           standard 754 for double precision floating-point arith-
  149. metic.
  150.  
  151.       ii. On other than VAX or IEEE machines,  run  the  original
  152. math
  153.           library,      formerly      "/usr/lib/libm.a",      now
  154. "/usr/lib/libom.a", if        nothing better is available.
  155.  
  156.      iii. The trigonometric functions sin/cos/tan/atan2 in  files
  157. "VAX/sincos.s",
  158.           "VAX/tan.s"  and "VAX/atan2.s" are different from those
  159. in
  160.           "IEEE/trig.c" and "IEEE/atan2.c".   The  VAX  assembler
  161. code uses the
  162.           true  value  of pi to perform argument reduction, while
  163. the C code uses
  164.           a machine value of PI (see "IEEE/trig.c").
  165.  
  166.  
  167. 2. A computer system that conforms to IEEE  standard  754  should
  168. provide
  169.                 sqrt(x),
  170.                 drem(x,p), (double precision remainder function)
  171.                 copysign(x,y),
  172.                 finite(x),
  173.                 scalb(x,N),
  174.                 logb(x) and
  175.                 rint(x).
  176.    These  functions  are  either  required  or recommended by the
  177. standard.
  178.    For convenience, a (slow) C implementation of these  functions
  179. is
  180.    provided in the file "IEEE/support.c".
  181.  
  182.    Warning:  The functions in IEEE/support.c are somewhat machine
  183. dependent.
  184.    Some modifications may be necessary to run them on a different
  185. machine.
  186.    Currently,  if compiled with a suitable flag, "IEEE/support.c"
  187. will work
  188.    on a National 32000, a Zilog 8000, a VAX, and a SUN  (cf.  the
  189. "Makefile"
  190.    in this directory). Invoke the C compiler thus:
  191.  
  192.         cc  -c -DVAX IEEE/support.c              ... on a VAX, D-
  193. format
  194.         cc -c -DNATIONAL IEEE/support.c         ... on a National
  195. 32000
  196.         cc -c  IEEE/support.c                   ... on other IEEE
  197. machines,
  198.                                                     we hope.
  199.  
  200.    Notes:
  201.       1. Faster versions of "drem" and  "sqrt"  for  IEEE  double
  202. precision
  203.          (coded  in  C  but  intended  for assembly language) are
  204. given at the
  205.          end of "IEEE/support.c" but  commented  out  since  they
  206. require certain
  207.          machine-dependent functions.
  208.  
  209.       2.  A  fast  VAX  assembler version of the system supported
  210. functions
  211.          copysign(),  logb(),  scalb(),  finite(),   and   drem()
  212. appears in file
  213.          "VAX/support.s".  A fast VAX assembler version of sqrt()
  214. is in
  215.          file "VAX/sqrt.s".
  216.  
  217. 3. Two formats are supported by all the standard elementary func-
  218. tions:
  219.    the  VAX D-format (56-bit precision), and the IEEE double for-
  220. mat
  221.    (53-bit precision).  The cbrt() in "IEEE/cbrt.c" is  for  IEEE
  222. machines
  223.    only.  The  functions  in files that end with ".s" are for VAX
  224. computers
  225.    only. The functions  in  files  that  end  with  ".c"  (except
  226. "IEEE/cbrt.c")
  227.    are  for  VAX and IEEE machines. To use the VAX D-format, com-
  228. pile the code
  229.    with  -DVAX;  to  use  IEEE  double  format  on  various  IEEE
  230. machines, see
  231.    "Makefile" in this directory).
  232.  
  233.     Example:
  234.         cc -c -DVAX sin.c               ... for VAX D-format
  235.  
  236.        Warning:  The  values  of floating-point constants used in
  237. the code are
  238.                 given in both hexadecimal and decimal.  The  hex-
  239. adecimal values
  240.                 are  the intended ones. The decimal values may be
  241. used provided
  242.                 that the compiler converts from decimal to binary
  243. accurately
  244.                 enough  to  produce the hexadecimal values shown.
  245. If the
  246.                 conversion is inaccurate, then one must know  the
  247. exact machine
  248.                 representation  of  the  constants  and alter the
  249. assembly
  250.                 language output from the compiler, or play tricks
  251. like
  252.                 the following in a C program.
  253.  
  254.                         Example: to store the floating-point con-
  255. stant
  256.  
  257.                              p1= 2^-6 * .F83ABE67E1066A (Hexadec-
  258. imal)
  259.  
  260.                         on  a  VAX  in C, we use two longwords to
  261. store its
  262.                         machine value and define  p1  to  be  the
  263. double constant
  264.                         at the location of these two longwords:
  265.  
  266.                         static   long    p1x[]  =  {  0x3abe3d78,
  267. 0x066a67e1};
  268.                         #define      p1      (*(double*)p1x)
  269.  
  270.     Note:  On a VAX, some functions have two codes. For  example,
  271. cabs()  has           one  implementation  in  "IEEE/cabs.c", and
  272. another in "VAX/cabs.s".
  273.            In this case, the assembly language  version  is  pre-
  274. ferred.
  275.  
  276.  
  277. 4. Accuracy.
  278.  
  279.             The errors in expm1(), log1p(), exp(), log(), cabs(),
  280. hypot()
  281.             and cbrt() are below 1 ULP (Unit in the Last  Place).
  282.  
  283.             The  error in pow(x,y) grows with the size of y. Nev-
  284. ertheless,
  285.             for integers x and y, pow(x,y)  returns  the  correct
  286. integer value
  287.             on  all  tested machines (VAX, SUN, NATIONAL, ZILOG),
  288. provided that
  289.             x to the power of y is representable exactly.
  290.  
  291.             cosh, sinh, acosh, asinh, tanh, atanh and log10  have
  292. errors below
  293.             about 3 ULPs.
  294.  
  295.             For  trigonometric  and  inverse  trigonometric func-
  296. tions:
  297.  
  298.                 Let [trig(x)] denote the value actually  computed
  299. for trig(x),
  300.  
  301.                 1) Those codes using the machine's value PI (true
  302. pi rounded):
  303.                    (source  codes:  IEEE/{trig.c,atan2.c},  asin-
  304. cos.c and atan.c)
  305.  
  306.                    The   errors   in   [sin(x)],   [cos(x)],  and
  307. [atan(x)] are below
  308.                    1    ULP    compared    with     sin(x*pi/PI),
  309. cos(x*pi/PI), and
  310.                    atan(x)*PI/pi  respectively,  where  PI is the
  311. machine's
  312.                    value  of   pi   rounded.   [tan(x)]   returns
  313. tan(x*pi/PI) within
  314.                    about   2   ULPs;  [acos(x)],  [asin(x)],  and
  315. [atan2(y,x)]
  316.                    return   acos(x)*PI/pi,   asin(x)*PI/pi,   and
  317. atan2(y,x)*PI/pi
  318.                    respectively to similar accuracy.
  319.  
  320.  
  321.                 2) Those using true pi (for VAX D-format only):
  322.                    (source  codes:  VAX/{sincos.s,tan.s,atan2.s},
  323. asincos.c and
  324.                    atan.c)
  325.  
  326.                    The  errors   in   [sin(x)],   [cos(x)],   and
  327. [atan(x)] are below
  328.                    1  ULP. [tan(x)], [atan2(y,x)], [acos(x)], and
  329. [asin(x)]
  330.                    have errors below about 2 ULPs.
  331.  
  332.  
  333.             Here are the results of some test runs to find  worst
  334. errors on
  335.             the VAX :
  336.  
  337.     tan    :   2.09  ULPs           ...1,024,000 random arguments
  338. (machine PI)
  339.     sin   :  .861  ULPs           ...1,024,000  random  arguments
  340. (machine PI)
  341.     cos    :   .857  ULPs           ...1,024,000 random arguments
  342. (machine PI)
  343.     (compared with tan, sin, cos of (x*pi/PI))
  344.  
  345.     acos  :  2.07  ULPs           .....200,000  random  arguments
  346. (machine PI)
  347.     asin   :   2.06  ULPs           .....200,000 random arguments
  348. (machine PI)
  349.     atan2 :  1.41  ULPs           .....356,000  random  arguments
  350. (machine PI)
  351.     atan   :   0.86  ULPs           ...1,536,000 random arguments
  352. (machine PI)
  353.     (compared with (PI/pi)*(atan, asin, acos, atan2 of x))
  354.  
  355.     tan   :  2.15  ULPs           ...1,024,000  random  arguments
  356. (true pi)
  357.     sin    :   .814  ULPs           ...1,024,000 random arguments
  358. (true pi)
  359.     cos   :  .792  ULPs           ...1,024,000  random  arguments
  360. (true pi)
  361.     acos   :   2.15  ULPs           ...1,024,000 random arguments
  362. (true pi)
  363.     asin  :  1.99  ULPs           ...1,024,000  random  arguments
  364. (true pi)
  365.     atan2  :   1.48  ULPs           ...1,024,000 random arguments
  366. (true pi)
  367.     atan  :  .850  ULPs           ...1,024,000  random  arguments
  368. (true pi)
  369.  
  370.     acosh :  3.30 ULPs          .....512,000 random arguments
  371.     asinh :  1.58 ULPs          .....512,000 random arguments
  372.     atanh :  1.71 ULPs          .....512,000 random arguments
  373.     cosh  :  1.23 ULPs          .....768,000 random arguments
  374.     sinh  :  1.93 ULPs          ...1,024,000 random arguments
  375.     tanh  :  2.22 ULPs          ...1,024,000 random arguments
  376.     log10 :  1.74 ULPs          ...1,536,000 random arguments
  377.     pow    :  1.79 ULPs          .....100,000 random arguments, 0
  378. < x, y < 20.
  379.  
  380.     exp   :  .768 ULPs          ...1,156,000 random arguments
  381.     expm1 :  .844 ULPs          ...1,166,000 random arguments
  382.     log1p :  .846 ULPs          ...1,536,000 random arguments
  383.     log   :  .826 ULPs          ...1,536,000 random arguments
  384.     cabs  :  .959 ULPs          .....500,000 random arguments
  385.     cbrt  :  .666 ULPs          ...5,120,000 random arguments
  386.  
  387.  
  388. 5. Speed.
  389.  
  390.         Some functions coded in VAX  assembly  language  (cabs(),
  391. hypot() and      sqrt()) are significantly faster than the corre-
  392. sponding ones in 4.2BSD.
  393.         In general, to  improve  performance,  all  functions  in
  394. "IEEE/support.c"
  395.         should be written in assembly language and, whenever pos-
  396. sible, should      be called via short subroutine calls.
  397.  
  398.  
  399. 6. j0, j1, jn.
  400.  
  401.         The modifications to these routines were only in  how  an
  402. invalid
  403.         floating point operations is signaled.
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.